Nomenclature, Endpoints, and Specifications
RESTful web APIs are designed around the concept of “resources” and “verbs”:
- Resources are the objects that the user acts upon. They are described as plural nouns.
- Verbs are the actual HTTP verbs, or actions, that are used to manipulate the resources.
Although there are more than thirty HTTP verbs, most of them are never used. For RESTful APIs, the five most commonly used verbs have been co-opted to reflect standard CRUD functionality.
| Verb | Description |
|---|---|
| GET | This is the standard HTTP verb that is used in virtually all web browsers. It is used to retrieve one or many existing resources, depending on URI and search parameters. |
| POST | This is the second most commonly used HTTP verb. In RESTful APIs, it is used to create a new instance of a resource. In database terms, this verb is used to insert a new record into the database. |
| PUT | This verb updates existing resources in their entirety. The resource must already exist in the application (database) in order for a PUT to be a valid action on it. |
| DELETE | This verb is used to delete one or more resources. It is up to the application to determine whether the data is physically or only logically deleted. |
| PATCH | This verb is used to make specific updates to a resource (unlike PUT calls, which update an entire resource). At this time, PATCH calls are only used in the Admin API. |
REST API URL Structure
The REST API URL is constructed as follows:
RESTful VERB https://apiname.com/<category>/<resource>
In this structure, apiname.com is the host and the remaining <category>/<resource> is the implementation (the part that actually does something).
Keep in mind that you never POST to a resource, only to a category. Also, be sure to add an endpoint URL for production and if available, any proof of concept/testing area you may have created.
Sample REST API URLs (Endpoints)
Fax Services API
GET https://api.securedocex.com/faxes/received
POST https://api.securedocex.com/faxes
DELETE https://api.securedocex.com/faxes/fax_id
Admin API
GET https://api.admin.securedocex.com/users/{customer-key}
POST https://api.admin.securedocex.com/users
DELETE https://api.admin.securedocex.com/numbers/{fax-numbers}
PATCH https://api.admin.securedocex.com/users/{customer-key}
Specifications
View the Fax Services API Specifications or view the Admin API Specifications.
Timezones
The timezone for all responses is UTC (Coordinated Universal Time).